Refer to appendix II, “C Code Usage,” for a discussion of Prograph data types and of the type macintosh. Types ABlock, ABlock@, and ABlock@@ are Mac types corresponding to a buffer, pointer to a buffer, and handle to a buffer, respectively. Many of the primitives in this category accept inputs that are direct, indirect (pointer), and doubly indirect (handle) references, and in fact also convert integers to pointers where appropriate. The Gets (such as get-integer) and Puts (such as put-real) output an incremental offset (original offset + size of data), to ensure proper positioning for the next Get or Put. In general, these primitives provide ways to manipulate heterogeneous data (obtained by reading from a file, for example) in memory buffers.
_________________________________________________
 
address-to-object *313*
Input types: integer; [ boolean ]
Output types: any
Description: Object is the Prograph Object at the specified Address. Address must have been generated by a call to object-to-address on the same machine (same address space), and you must be certain that the object still exists at that address. Release? is FALSE by default. If Release?, then Address is not valid.
See also: object-to-address
_________________________________________________
 
block-address *313*
Input types: ABlock
Output types: integer
Description: Address is the address of the first character in Block. Block should be locked whenever Address is taken or used.
See also: string-address
_________________________________________________
 
block-size *314*
Input types: macintosh
Output types: integer
Description: Size is the value of the size field of Mac.
See also: new-block
_________________________________________________
  compact-memory *314*
Description: Compacts memory. Use this primitive if you are using Macintosh methods which require a lot of memory.
_________________________________________________
 
from-handle *314*
Input types: macintosh
Output types: integer
Description: Mac must be a handle to a Macintosh structure, and Address is the address of the handle’s master pointer.
See also: to-handle, to-pointer, from-pointer
_________________________________________________
 
from-pointer *314*
Input types: macintosh
Output types: integer
Description: Mac must be a pointer to a Macintosh structure, and Address is the address of that structure.
Description: Value is an integer of length Size bytes, read from Buffer starting at Offset bytes. Size must be 1, 2, or 4. NextOffset is Offset + Size.
See also: put-integer, get-point, get-real, get-rect, get-string, get-text, sign-extend
_________________________________________________
 
get-point *315*
Input types: ABlock[@[@]] | integer; integer
Output types: ABlock[@[@]] | integer; integer; Point
Description: aPoint is a point obtained by reading four bytes from Buffer starting at Offset bytes. NextOffset is Offset + 4.
See also: put-point, get-integer, get-real, get-rect, get-string, get-text
_________________________________________________
 
get-real *315*
Input types: ABlock[@[@]] | integer; integer
Output types: ABlock[@[@]] | integer; integer; real
Description: Value is a real of length Size bytes, read from Buffer starting at Offset bytes. Size must be be 4, 8, or 10. NextOffset is Offset + Size.
See also: put-real, get-integer, get-point, get-rect, get-string, get-text
_________________________________________________
 
get-rect *316*
Input types: ABlock[@[@]] | integer; integer
Output types: ABlock[@[@]] | integer; integer; Rect
Description: aRect is a rectangle obtained by reading eight bytes from Buffer starting at Offset bytes. NextOffset is Offset + 8.
See also: put-rect, get-integer, get-point, get-real, get-string, get-text
Description: aString is a string of length N bytes, where N is the one-byte integer read from Buffer starting at Offset, and the N bytes of aString are read from Buffer starting at Offset+1. NextOffset is Offset+N+1.
See also: put-string, get-integer, get-point, get-real, get-rect, get-text
Description: aString is a string of length Size bytes, read from Buffer starting at Offset bytes. Size must be greater than or equal to 0 and less than or equal to 65535. NextOffset is Offset + Size.
See also: put-text, get-integer, get-point, get-real, get-rect, get-string
_________________________________________________
 
lock-block *317*
Input types: ABlock
Description: Locks the handle containing Block.
See also: unlock-block
_________________________________________________
 
lock-string *317*
Input types: string
Description: Locks the handle containing aString.
See also: unlock-string
_________________________________________________
 
make-direct *317*
Input names: Type; Size
Input types: string; integer
Output types: external
Description: Block is an external structure block of size Size and type Type. Type can be any name listed under External Structures in the Info window.
See also: make-handle, make-pointer
_________________________________________________
 
make-handle *317*
Input names: Type; Size
Input types: string; integer
Output types: external@@
Description: Handle is a handle to a structure of size Size and type Type. Type can be any name listed under External Structures in the Info window. The user must use the Mac Toolbox call DisposHandle to free the memory allocated to the handle.
See also: make-direct, make-pointer
_________________________________________________
 
make-pointer *318*
Input names: Type; Size
Input types: string; integer
Output types: external@
Description: Pointer is a pointer to a structure of size Size and type Type. Type can be any name listed under External Structures in the Info window. The user must use the Mac Toolbox call DisposPtr to free the memory allocated to the pointer.
See also: make-direct, make-handle
_________________________________________________
 
new-block *318*
Input types: integer
Output types: ABlock
Description: Block is a new block of Size bytes.
See also: block-size
_________________________________________________
 
object-to-address *319*
Input types: any; [ boolean ]
Output types: integer
Description: Address is the address of any Prograph object. Keep? is FALSE by default. If TRUE, then Address is always valid and the Object is not deleted. To recover memory in this case, address-to-object must be TRUE.
Description: Value is converted into an integer of Size bytes, which is then put into Buffer starting at Offset. Size must be 1, 2, or 4. NextOffset is Offset + Size.
See also: get-integer, put-point, put-real, put-rect, put-string, put-text
_________________________________________________
 
put-point *319*
Input types: ABlock[@[@]] | integer; integer; Point
Output types: ABlock[@[@]] | integer; integer
Description: The four bytes of aPoint are put into Buffer at Offset. NextOffset is Offset + 4.
See also: get-point, put-integer, put-real, put-rect, put-string, put-text
_________________________________________________
 
put-real *320*
Input types: ABlock[@[@]] | integer; integer; integer; real
Output types: ABlock[@[@]] | integer; integer
Description: Converts value into a floating point value of Size bytes, which is then put into Buffer starting at Offset. Size must be 4, 8, or 10. NextOffset is Offset + Size.
See also: get-real, put-integer, put-point, put-rect, put-string, put-text
_________________________________________________
 
put-rect *320*
Input types: ABlock[@[@]] | integer; integer; Rect
Output types: ABlock[@[@]] | integer; integer
Description: Puts 8 bytes of aRect into Buffer at Offset. NextOffset is Offset + 8.
See also: get-rect, put-integer, put-point, put-real, put-string, put-text
Description: Puts N+1 bytes into Buffer starting at Offset, where N is the mimimum of 255 and the length of aString. First byte is N; the remaining N bytes are from aString. NextOffset is Offset+N+1.
See also: get-string, put-integer, put-point, put-real, put-rect, put-text
Description: Puts Size bytes from aString into Buffer starting at Offset. Size must be greater than or equal to 0 and less than or equal to 65535. NextOffset is Offset+Size.
See also: get-text, put-integer, put-point, put-real, put-rect, put-string
_________________________________________________
 
string-address *321*
Input types: string
Output types: integer
Description: Address is the address of the first character in aString. aString should be locked whenever Address is taken or used.
See also: block-address
_________________________________________________
 
to-handle *321*
Input types: integer
Output types: macintosh
Description: Address is the address of a master pointer to a Macintosh structure, and Mac is a handle to that structure.
See also: from-handle, to-pointer, from-pointer
_________________________________________________
 
to-pointer *322*
Input types: integer
Output types: macintosh
Description: Address is the address of a Macintosh structure, and Mac is a pointer to that structure.
See also: from-pointer, to-handle, from-handle
_________________________________________________
 
unlock-block *322*
Input types: ABlock
Description: Unlocks the handle containing Block.
See also: lock-block
_________________________________________________
 
unlock-string *322*
Input types: string
Description: Unlocks the handle containing aString.
